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PREFACE 


Current  Department  of  Defense  simulation  research  centers  on  real-time,  interactive  sim¬ 
ulation  of  realistic,  complex,  “virtual  worlds”  represent  the  coalescence  of  a  diverse  set  of 
virtual,  constructive,  and  live  simulations  occurring  at  various  locations  throughout  the  world. 
This  effort  is  collectively  known  as  Distributed  Interactive  Simulation  (DIS).  Its  purpose  is  to 
allow  dissimilar  autonomous  simulation  nodes  to  interoperate  in  real-time,  interactive,  dis¬ 
tributed  simulations.  Inter-node  communication  is  achieved  by  exchanging  DIS  protocol  data 
units  (PDU).  To  facilitate  the  development  of  simulation  application  programs  that  use  the 
DIS  protocol,  the  Simulation  Methodology  Branch  of  the  Advanced  Computational  and  Infor¬ 
mational  Sciences  Directorate,  U.S.  Army  Research  Laboratory  (ARL),  developed  a  set  of 
DIS  software  management  programs,  collectively  referred  to  as  the  DIS  Network  Manager. 

The  author  wishes  to  acknowledge  the  Naval  Post  Graduate  school  and  Dr.  David  Pratt  for 
providing  the  software  from  which  an  early  version  of  the  DIS  Network  Manager  was  devel¬ 
oped.  Though  most  of  the  software  has  been  rewritten,  the  User  Datagram  Protocol  (UDP) 
networking  code  is  still  largely  unchanged.  Software  developers  that  have  also  contributed  in¬ 
clude  Holly  Ingham  and  Geoffrey  Sauerbom,  both  from  the  ARL. 
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1.  INTRODUCTION 


Current  Department  of  Defense  simulation  research  centers  on  real-time,  interactive  sim¬ 
ulation  of  realistic,  complex,  “virtual  worlds”  represent  the  coalescence  of  a  diverse  set  of 
virtual,  constructive,  and  live  simulations  occurring  at  various  locations  throughout  the  world. 
This  effort  is  collectively  known  as  Distributed  Interactive  Simulation  (DIS).  Its  purpose  is  to 
allow  dissimilar  autonomous  simulation  nodes  to  interoperate  in  real-time,  interactive,  dis¬ 
tributed  simulations.  Each  simulation  node  maintains  and  conveys  the  state  of  one  or  more 
simulation  entities.  Simulation  nodes  communicate  simulation  entity  states  over  both  local 
and  wide  area  networks  by  exchanging  standard  DIS  protocol  data  units  (PDUs). 

The  Simulation  Methodology  Branch  (SMB)  of  the  Advanced  Computational  and  Infor¬ 
mational  Sciences  Directorate  (ACISD),  U.S.  Army  Research  Laboratory  (ARL),  developed 
a  set  of  DIS  software  management  programs,  collectively  referred  to  as  the  DIS  Network  Man¬ 
ager.  These  programs  are  designed  to  facilitate  the  development  of  software  application  pro¬ 
grams  that  use  the  DIS  protocol  and  to  explore  advancing  the  DIS  protocol  itself  through  the 
addition  of  new  PDUs  and  alternate  PDU  management  techniques. 

2.  GENERAL 

The  DIS  Network  Manager  provides  application  programs  with  a  programmatic  interface 
to  a  DIS  network.  In  this  report,  a  DIS  network  is  defined  to  be  any  local  area  network  (LAN) 
on  which  DIS  application  programs^  are  operating.  The  DIS  Network  Manager  comprises  two 
functional  components.  The  first,  called  disjngr,  establishes  and  manages  a  connection  to  a 
DIS  network.  ITie  second  component,  called  libdis,  is  a  software  library  that  works  in  conjunc¬ 
tion  with  the  disjngr  to  facilitate  constructing,  sending,  receiving,  and  interpreting  DIS  PDUs. 

2.1  DIS 

DIS  operates  under  the  notion  that  a  diverse  and  large  number  of  simulated  entities  may 
participate  and  interact  in  real  time  during  a  single  simulation  exercise.  Successful  interaction 
depends  on  each  simulated  entity’s  physical  state  and  actions  being  communicated  to  all  other 
simulated  entities  in  a  timely,  succinct,  and  consistent  fashion.  DIS  provides  a  protocol  that 
describes  the  philosophy  and  requisite  information  needed  to  simulate  entities  in  such  an  envi¬ 
ronment. 

Successful  DIS  simulation  exercises  eire  dependent  in  part  on  the  unique  identification  of 
each  simulated  entity.  Simulated  entities  in  DIS  are  uniquely  identified  by  site,  host,  and  entity 
numbers.  Each  physical  site  participating  in  an  exercise  is  identified  by  a  unique  number.  Fur¬ 
ther,  each  computer  host  at  a  site  is  identified  by  a  unique  number.  Lastly,  each  entity  that  is 
being  simulated  by  a  computer  host  is  assigned  a  number  unique  to  that  host. 

Communication  of  entity  states  and  actions  is  accomplished  by  using  predefined  DIS 
PDUs.  PDUs  convey  the  current  state  of  a  simulated  entity  or  a  simulation  event  involving  one 
or  more  entities,  such  as  a  collision.  Within  the  PDU,  details  concerning  the  state  or  event  are 
specified  via  enumeration  and  bit-encoded  values. 


^  The  term  “DIS  applications”or  “DIS  application  programs”  refers  to  programs  that  use  the  DIS  commu¬ 
nications  protocol. 
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DIS  exercises  are  conducted  over  both  local  and  wide  area  networks.  They  consist  of  simu¬ 
lation  hosts  running  applications  that  simulate  one  or  more  entities.  Each  host  is  responsible 
for  transmitting  the  absolute  truth  about  the  entity(ies)  it  is  simulating  to  all  other  hosts  in  an 
exercise.  It  is  similarly  responsible  for  determining  how  its  simulated  entity(ies)  are  perceived 
and  affected  by  incoming  PDUs  (DIS  1994). 

22  DIS  Manager 

The  disjngr  is  a  software  program  that  provides  network  communications  services  for  ap¬ 
plication  programs.  It  uses  user  datagram  protocol  (UDP)  broadcast  to  transmit  outgoing 
PDUs  over  the  DIS  network  to  other  simulation  hosts.  It  listens  to  the  network  and  receives 
all  incoming  PDUs  that  other  simulation  hosts  have  transmitted. 

The  disjngr  can  communicate  with  other  disjngrs  or  directly  with  other  DIS  applications 
that  are  not  designed  to  use  a  disjngr.  For  DIS  applications  to  exchange  PDUs  with  other  ap¬ 
plications,  the  only  networking  requirement  is  that  all  applications  transmit  and  receive  PDUs 
over  the  same  UDP  ports.  While  the  disjngr  uses  default  UDP  ports  for  sending  and  receiving 
PDUs,  the  port  numbers  can  be  changed  through  conunand-line  arguments.  This  allows  for 
the  concurrent  development  and  testing  of  multiple  DIS  applications  on  the  same  LAN  with¬ 
out  interference  from  other  DIS  applications  or  exercises. 

The  DIS  Network  Manager  departs  from  the  notion  of  a  single  host  computer  running  a 
single  simulation  application.  Rather,  it  is  designed  to  permit  multiple  simulation  applications 
to  run  from  a  single  host  computer.  Due  to  the  inherent  nature  of  UDP  to  only  permit  a  single 
communications  channel  per  host  computer,  a  client-server  architecture  is  employed  by  the 
disjngr  to  enable  multiple  applications  to  operate  on,  and  transmit  their  PDUs  from,  a  single 
host  computer. 

The  client-server  protocol  implemented  between  the  disjngr  and  application  programs 
uses  UNIX  transport  control  protocol  (TCP)  internet  protocol  (IP)  to  exchange  information. 
Client  programs  connect  to  the  disjngr  to  use  its  send  and  receive  services.  The  disjngr  estab¬ 
lishes  a  UDP  connection  to  the  DIS  network.  It  takes  outgoing  PDUs  from  its  client  programs 
and  transmits  them  over  the  DIS  network.  Incoming  PDUs  that  the  disjngr  receives  from  the 
DIS  network  are  passed  back  to  its  application  programs  (see  Figure  1). 

An  interesting  feature  of  this  architecture  is  that  client  programs  who  send  PDUs  will  in 
turn  receive  them  from  the  disjngr  as  incoming  PDUs.  This  can  facilitate  an  application’s 
processing  of  entities  as  the  DIS  protocol  requires  that  applications  maintain  two  states  for 
each  entity  in  their  responsibility:  1)  the  high  fidelity  absolute  state  of  an  entity  as  known  only 
by  the  application,  and  2)  the  “ground  truth”  state  of  an  entity  as  it  is  presented  to  and  repre¬ 
sented  by  all  applications  participating  in  the  simulation  exercise.  Receipt  of  its  own  PDUs  en¬ 
ables  an  application  to  more  easily  mziintain  the  “ground  truth”  state  of  its  own  entities. 

Default  configuration  of  the  permits  from  one  to  four  client  programs  to  utilize  the 

services  of  a  single  disjngr.  It  can  be  conjBgured  through  a  command-line  argument  to  handle 
up  to  eight  clients.  This  number  was  arbitrarily  chosen  to  impose  a  practical  limit  on  the  num¬ 
ber  of  clients  for  any  one  disjngr.  A  relatively  small  number  was  chosen  because  of  the  DIS 
entity  identification  scheme  that  requires  entities  be  assigned  a  unique  number  between 
0-65,535  for  each  simulation  host.  K  more  than  one  simulation  application  is  running  on  a 
single  host,  then  entity  id  numbers  must  be  unique  across  all  applications  on  that  host.  The  DIS 
Network  Manager  ensures  such  uniqueness  by  assigning  a  range  of  entity  id  numbers  to  each 
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DIS  Network 


Key: 

O  Simulation  Host 
^  Outgoing  PDU 
^  Incoming  PDU 

Simulation  Application 


Figure  1.  disjngr  Network  Connections 


application  will  be  assigned  the  range  0—16,383  to  use  for  entity  id  numbers.  The  second  ap¬ 
plication  will  use  numbers  in  the  range  16,384—32,767,  etc. 

Another  service  offered  by  the  disjngr  is  PDU  filtering.  PDUs  are  filtered  at  the  PDU  lev¬ 
el.  That  is,  they  are  filtered  by  PDU  type.  A  client  application  program  can  instruct  the  disjngr 
to  not  send  it  any  PDUs  of  a  specified  type,  such  as  FirePDU  or  ServiceRequestPDU.  Thus, 
applications  will  only  receive  those  types  of  PDUs  that  they  specify.  This  prevents  an  applica¬ 
tion  program  firom  having  to  process  PDUs  that  it  can  not  or  does  not  want  to  handle. 

Lastly,  the  disjngr  queues  incoming  PDUs  for  each  client  application  program  until  the 
client  requests  them.  The  philosophy  of  the  DIS  Network  Manager  is  that  client  application 
programs  will  process  PDUs  as  fast  as  they  are  able.  When  applications  are  ready  to  receive 
the  next  incoming  PDU,  they  request  it  from  the  disjngr.  This  scheme  simplifies  the  design 
of  applications  since  they  do  not  have  to  be  developed  to  handle  incoming  PDUs  asynchro¬ 
nously. 

2J  DISLibraiy 

The  second  component  of  the  DIS  Network  Manager,  libdis,  is  a  library,  or  collection  of 
software  routines,  for  use  by  application  programs  utilizing  the  disjngr.  It  provides  a  consis¬ 
tent,  easy-to-use  means  of  creating,  interpreting,  sending,  and  receiving  PDUs.  It  also  handles 
the  TCP/IP  based  client-server  communication  between  application  programs  and  the 
disjngr. 
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Application  programs  using  the  services  of  the  disjngr  first  connect  to  it,  via  the  library 
routine  called  dis_open().  This  routine  opens  a  TCP/IP-based  connection  to  the  disjngr 
through  which  all  future  communication  will  occur.  In  response,  the  disjngr  sends  a  message 
back  to  the  application  program  containing  the  protocol  version,  exercise  identification  num¬ 
ber,  and  range  of  available  entity  identification  numbers  for  use  by  that  application  when 
creating  entities. 

For  filtering  PDUs,  two  routines  are  available  to  application  programs:  dis_register  jpdu() 
and  dis_ignore_pdu().  When  application  programs  first  connect  to  the  disjngr,  they  default 
to  receive  no  incoming  PDUs  from  the  disjngr.  They  must  register  with  the  disjngr  those 
PDUs  that  they  wish  to  receive.  This  is  done  by  listing  the  desired  PDU  types  via  the  dis_regis- 
ter_pdu()  routine.  This  ensures  that  application  programs  will  not  receive  unexpected  PDU 
types.  The  dis_ignore_pdu()  routine  allows  application  programs  to  stop  receiving  PDU  types 
that  were  previously  registered  for  receipt. 

The  library  provides  a  set  of  routines  whose  names  take  the  form  of  get_PDC/typePDU, 
where  PDUtype  is  the  name  of  a  type  of  PDU.  For  example,  to  create  an  EntityState  PDU  the 
routine  get_EntityStatePDU()  would  be  used.  These  routines  create  C  data  structures  that  re¬ 
flect  the  fields  in  the  PDU.  The  “protocol  header”  field  of  the  newly  created  PDU  is  filled  by 
the  libdis  PDU  creation  routines.  It  is  the  application  programs  responsibility  to  fill  all  of  the 
remaining  fields  in  a  PDU  with  appropriate  values. 

Application  programs  send  PDUs  via  the  dis_send()  routine.  This  routine  takes  as  its  argu¬ 
ment  a  pointer  to  a  C-structured  PDU  as  created  using  one  of  the  get_PDUtypeFD\JQ  rou¬ 
tines.  These  can  be  complex  structures  containing  many  smaller  structures  and  even  linked  lists 
of  other  structures.  The  dis_send()  library  routine  compresses  the  C— structured  PDU  into  a 
single  contiguous  string  of  bytes  and  fills  in  the  “length”  field  of  the  PDU  protocol  header  be¬ 
fore  sending  the  PDU  to  the  disjngr  for  transmission  over  the  DIS  network. 

A  complementary  routine  to  dis_send()  is  dis_read().  This  routine  is  used  by  application 
programs  to  receive  the  next  incoming  PDU  from  the  disjngr".  PDUs  from  the  disjngr  are  re¬ 
ceived  as  a  single  contiguous  string  of  bytes.  dis_read()  converts  those  b^es  into  an  appropri¬ 
ate  C-structured  PDU  for  easier  use  by  the  application  program.  Additionally,  dis_read()  re¬ 
turns  an  integer  that  identifies  the  type  of  PDU  that  was  received. 

To  assist  in  debugging  DIS  application  programs,  libdis  provides  the  capability  to  print 
PDUs.  The  print  routines,  prmt_PDUtypeQ},  print  C-structured  PDUs  in  ASCII  and  identify 
the  respective  data  type  of  each  PDU  field.  The  DIS  standards  specify  the  data  type  of  each 
field  in  a  PDU  by  len^h  and  type.  For  example,  the  “protocol  version”  field  of  PDUs  is  defined 
to  be  an  8-bit  unsigned  integer.  Appendix  A  contains  output  generated  by  the 
print_EntityState()  routine  for  a  sample  EntityState  PDU. 

2.4  Other  Features  and  Utility  Programs 

A  sample  client  application  program  was  created  that  illustrates  a  DIS  application  program 
designed  to  use  the  DIS  Network  Manager.  This  program  demonstrates  the  rudiments  of  an 
application  program  connecting  to  the  disjngr,  registering  to  receive  PDUs,  creating  a  PDU, 
sending  the  PDU,  and  printing  any  incoming  PDUs. 

A  second,  more  sophisticated  application  program  was  created  that  provides  an  X/Motif- 
based  graphical  user  interface  for  creating  sample  PDUs  that  can  be  sent  out  over  the  DIS  net¬ 
work.  This  program,  called  clientX,  offers  a  pull-down  menu  of  all  of  the  available  PDU  types 
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that  a  user  may  send  along  with  a  popup  window  for  setting  the  number  of  PDUs  to  send.  A 
“Send”  button  is  provided  that,  when  pushed,  will  create  a  sample  PDU  for  each  type  and  num¬ 
ber  of  selected  PDUs  in  the  menu  and  send  them  to  the  disjngr  for  transmission  across  the 
DIS  network.  More  than  one  type  of  PDU  can  be  selected  to  be  sent  at  a  time. 

Functions  are  provided  in  the  libdis  library  to  enable  the  logging  of  PDUs.  PDUs  can  be 
logged  with  an  optional  time-stamped  header,  by  direction  (incoming,  outgoing,  or  both),  and 
in  one  of  three  formats:  ASCII,  binary,  or  ASCII-binary.  The  optional  header  precedes  each 
logged  PDU  in  a  log  file  and  contains  a  time  stamp,  the  PDU  type,  and  “INCOMING”  or 
“OUTGOING”  designation  to  indicate  whether  the  logged  PDU  was  sent  and/or  received  by 
the  the  logging  program.  ASCII  formatted  PDUs  utilize  the  pnntJPDUtypeO  routines  in  log¬ 
ging  PDUs  to  a  file.  Binary  formatted  PDUs  are  logged  in  straight  binary.  The  ASCII-binary 
format  logs  PDUs  by  representing  a  PDU’s  binary  format  using  ASCII  “ones”  and  “zeros.” 
This  presents  the  actual  binary  bit  stream  for  a  PDU  in  a  human  readable  form.  It  requires 
considerably  less  space  than  straight  ASCII  and  is  useful  when  debugging  PDUs  to  examine 
the  actual  bit  values  of  a  PDU.  Appendix  B  contains  sample  PDUs  logged  in  both  the  straight 
ASCII  format  and  ASCII— binary  format. 

Both  the  disjngr  and  clientX  programs  are  capable  of  logging  PDUs.  Logging  via  the 
disjngr  is  enabled  through  command  line  arguments.  The  clientX  program  has  a  popup  win¬ 
dow  through  which  logging  can  be  turned  on  or  off  and  the  various  combinations  of  header, 
PDU  direction,  and  format  can  be  specified.  Using  the  disjngr  to  log  PDUs  allows  logging 
of  all  PDUs  on  a  DIS  network  or  simply  those  PDUs  that  originate  from  the  dis  mgr’s  clients. 
Logging  PDUs  at  the  client  program  level  allows  for  the  logging  of  all  PDUs  sent  and/or  re¬ 
ceived  by  a  particular  DIS  application. 

Complementing  the  logging  capability  is  a  set  of  utility  programs  for  converting  between 
the  straight  binary  and  the  ASCII— binary  log  formats.  Additionally,  a  program  is  provided  to 
replay  logged  PDUs.  This  program  plays  back  time-stamped  binary  formatted  log  files.  It  re¬ 
plays  the  PDUs  at  the  original  rate  at  which  they  were  sent. 

3.  FUTURE  DEVELOPMENTS 

One  of  the  merits  of  the  in-house  developed  DIS  Network  Manager  is  the  control  over  its 
development  and  operation.  It  readily  supports  the  development  and  testing  of  new  DIS 
PDUs.  Similarly,  alternative  schemes  for  exploring  more  efficient  use  of  the  DIS  network  can 
be  tested.  Filtering  PDUs  at  a  level  above  application  programs  alleviates  the  application  pro¬ 
grams  of  this  burden,  freeing  them  to  do  more  processing  of  their  designed  tasks. 

A  more  sophisticated  PDU  filtering  scheme  is  under  consideration  as  a  future  enhance¬ 
ment  to  the  DIS  Network  Manager.  Currently,  PDUs  are  filtered  by  type.  Other  schemes  could 
include  filtering  based  on  the  source,  time,  and  entity  location.  In  an  experiment  involving 
“live”  entities,  it  may  be  desirable  for  other  live  entities  to  ignore  their  PDUs  if  they  are  redun¬ 
dant.  For  instance,  in  an  exercise  involving  live  and  simulated  tanks,  the  real  tanks  don’t  need 
to  receive  EntityState  PDUs  about  other  real  tanks  that  they  can  physically  see.  PDUs  could 
be  filtered  if  they  are  outdated  due  to  slow  or  congested  networks.  PDUs  could  also  be  filtered 
based  on  their  relative  impact  on  the  receiving  entity.  In  other  words,  if  an  incoming  PDU  will 
have  no  immediate  or  future  impact  on  the  receiving  entity  then  it  can  be  filtered  out  by  the 
disjngr. 
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Another  enhancement  is  a  more  transparent  method  of  generating  entity  identification 
numbers.  Entity  identification  numbers  are  supposed  to  be  unique  within  each  simulation 
host.  Since  the  disjngr  acts  as  a  simulation  host,  but  comprises  potentially  more  than  one  simu¬ 
lation  application,  all  entity  identification  numbers  should  be  generated  by  the  disjngr ,  not 
each  of  its  client  application  programs  as  is  currently  done. 

Future  versions  of  the  DIS  Network  Manager  will  use  an  interrupt  driven  scheme  to  notify 
client  application  programs  of  the  arrival  of  PDUs.  This  will  alleviate  the  application  programs 
from  having  to  continually  poll  the  disjngr  for  incoming  PDUs.  The  libdis  library  will  generate 
a  separate  process  for  each  client  program  that  will  notify  the  client  program  when  a  PDU  has 
arrived.  In  this  way,  client  programs  will  not  need  to  regularly  and  frequently  call  dis_read() 
to  check  for  incoming  PDUs.  Instead,  they  will  only  need  to  call  it  when  they  have  been  sig¬ 
naled  that  a  PDU  is  pending. 

4.  CONCLUSION 

The  DIS  Network  Manager  was  developed  to  facihtate  the  creation  of  applications  pro¬ 
grams  designed  to  operate  in  a  DIS  environment.  It  provides  a  DIS  network  level  interface 
through  which  application  programs  can  easily  send  and  receive  DIS  PDUs.  Built-in  routines 
give  application  programs  easy  control  over  PDU  creation  and  flow  control.  The  DIS  Network 
Manager  is  flexible  and  can  be  easily  expanded  to  support  experimentation  with  new  and  al¬ 
tered  PDU  types  and  network  communication  control.  Enhancements  are  currently  underway 
to  provide  improved  logging,  playback,  analysis,  and  interactive  generation  of  PDUs. 
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APPENDIX  A: 
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Sample  Output  from  print  EntityStatePDUO  Routine 


Ih&libdis  library  contains  simple  debugging  routines  that  print  DIS  PDUs  in  ASCII.  Below 
is  an  example  of  the  output  for  an  EntityStatePDU.  The  values  for  the  fields  in  the 
EntityStatePDU  may  not  be  correct  or  valid  as  this  is  just  sample  data  used  to  test  the  routine. 
The  version  of  the  DIS  protocol  being  used  is  2.0.2. 

->Entity  State  PDU: 

{ 

protocoLheader  =  { 

protocoLversion  =  2  (8  bit  unsigned  int) 
exercise_ident  =  1  (8  bit  unsigned  int) 
pdutype  =  1  (8  bit  enum) 
length  =  0  (8  bit  unsigned  int) 

}; 

entity_id  =  { 

site  =  37  (16  bit  unsigned  int) 
host  =  63  (16  bit  unsigned  int) 
entity  Jd  =  1  (16  bit  unsigned  int) 

}; 

forcejd  =  2  (8  bit  enum) 

entity_type  =  { 

entity_kind  =  0  (8  bit  enum) 
domain  =  0  (8  bit  enum) 
country  =  0  (16  bit  enum) 
category  =  0  (8  bit  enum) 
subcategory  =  0  (8  bit  enum) 
specific  =  4  (8  bit  enum) 
extra  =  0  (8  bit  enum) 

}; 

alt_entity_type  =  { 

entity_kind  =  0  (8  bit  enum) 
domain  =  0  (8  bit  enum) 
country  ==  0  (16  bit  enum) 
category  =  0  (8  bit  enum) 
subcategory  =  0  (8  bit  enum) 
specific  =  0  (8  bit  enum) 
extra  =  0  (8  bit  enum) 

}; 

time_stamp  =  0  (32  bit  unsigned  int) 

entity_location  =  { 

x=  1.000000  (64  bit  float) 
y  =  2.000000  (64  bit  float) 
z  =  3.000000  (64  bit  float) 

}; 

entity_linear_velocity  =  { 

X- 0.000000  (32  bit  float) 
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y  =  0.000000  (32  bit  float) 

2  =  0.000000  (32  bit  float) 

}; 

entity_orientation  =  { 

psi  =  0.000000  (32  bit  float) 
theta  =  0.000000  (32  bit  float) 
phi  =  0.000000  (32  bit  float) 

}; 

dead_reckon_params  =  { 

algorithm  =  0  (8  bit  enum) 
linear_accel  =  { 

x  =  0.000000  (32  bit  float) 
y  =  0.000000  (32  bit  float) 

2  =  0.000000  (32  bit  float) 

}; 

angular_velocity  =  { 

X  =  0.000000  (32  bit  float) 
y  =  0.000000  (32  bit  float) 

2  =  0.000000  (32  bit  float) 

}; 

}; 

entity_appearance  =  0  (32  bit  enum) 
entity_marking  =  { 

char_set  =  0x0  (8  bit  enum) 

char_strings[ll]  (8  bit  unsigned  int)  =  00000000000 

}; 

capabilities  =  0x0  (32  bin  boolean) 
num_articulate_params  =  2  (8  bit  unsigned  int) 
articulat_params_head  =  { 

[0]  =  { 

change  =  10  (16  bit  unsigned  int) 
id_attached_to  =  11  (16  bit  unsigned  int) 
parameter_type  =  12  (32  bit  enum) 

parameter_value[8]  (8  bit  unsigned  int)  =  31  255  245  200  0  4  24 144 

}; 

[i]  =  { 

change  =  20  (16  bit  unsigned  int) 
id_attached_to  =  21  (16  bit  unsigned  int) 
parameter_type  =  22  (32  bit  enum) 

parameter_value[8]  (8  bit  unsigned  int)  =  32  255  245  200  239  255  245  128 
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Sample  PDU  Log  Formats 


The  DIS  Network  Manager  is  capable  of  logging  PDUs  in  one  of  several  formats;  straight 
binary,  straight  ASCII,  or  ASCII-binary.  Additionally,  each  PDU  may  be  tagged  with  a  time- 
stamped  header  that  shows  the  length  of  the  PDU  in  bytes,  the  time  it  was  sent  or  received, 
and  whether  it  was  incoming  or  outgoing.  Incoming  only,  outgoing  only,  or  both  incoming  and 
outgoing  PDUs  may  be  logged. 

Below  is  a  sample  of  an  EntityStatePDU  logged  in  two  different  formats:  straight  ASCII 
and  ASCII-binary.  The  values  for  the  fields  in  the  EntityStatePDU  may  not  be  correct  or  valid 
as  this  is  just  sample  data  used  in  generating  a  PDU  that  could  be  logged. 

Straight  ASCII  Log  Format 

Below  is  an  EntityStatePDU  logged  in  the  straight  ASCII  format  with  a  header.  The  ver¬ 
sion  of  the  DIS  protocol  being  used  is  2.0.3. 


176  Thu  Oct  20  08:07: 10.757701  INCOMING 
Entity  State  PDU: 

{ 

protocoLheader  =  { 

protocoLversion  =  3  (8  bit  unsigned  int) 
exercisejdent  =  1  (8  bit  unsigned  int) 
pdutype  =  1  (8  bit  enum) 
length  =  176  (8  bit  unsigned  int) 
time_stamp  =  0  (8  bit  unsigned  int) 

}; 

entity_id  =  { 

site  =  37  (16  bit  unsigned  int) 
host  =  53  (16  bit  unsigned  int) 
entityjd  =  1  (16  bit  unsigned  int) 

}; 

force_id  =  2  (8  bit  enum) 

entity_type  =  { 

entity_kind  =  0  (8  bit  enum) 
domain  =  0  (8  bit  enum) 
country  =  0  (16  bit  enum) 
category  =  0  (8  bit  enum) 
subcategory  =  0  (8  bit  enum) 
specific  =  4  (8  bit  enum) 
extra  =  0  (8  bit  enum) 

}; 

alt_entity__type  =  { 

entity_kind  =  0  (8  bit  enum) 
domain  =  0  (8  bit  enum) 
country  =  0  (16  bit  enum) 
category  =  0  (8  bit  enum) 
subcategory  ==  0  (8  bit  enum) 
specific  =  0  (8  bit  enum) 
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extra  =  0  (8  bit  enum) 


}; 

entity_location  =  { 

X  =  1 .000000  (64  bit  float) 
y  =  2.000000  (64  bit  float) 

2  =  3.000000  (64  bit  float) 

}; 

entity_linear_velocity  =  { 

x  =  0.000000  (32  bit  float) 
y  =  0.000000  (32  bit  float) 

2  =  0.000000  (32  bit  float) 

}; 

entity_orientation  =  { 

psi  =  0.000000  (32  bit  float) 
theta  =  0.000000  (32  bit  float) 
phi  =  0.000000  (32  bit  float) 

}; 

dead_reckon_params  =  { 

algorithm  =  0  (8  bit  enum) 
linear_accel  =  { 

x  =  0.000000  (32  bit  float) 
y  =  0.000000  (32  bit  float) 

2  =  0.000000  (32  bit  float) 

}; 

angular_velocity  =  { 

x  =  0.000000  (32  bit  float) 
y  =  0.000000  (32  bit  float) 

2  =  0.000000  (32  bit  float) 

}; 

}; 

entity _appearance  =  0  (32  bit  enum) 
entity_marking  -  { 

char_set  =  0x0  (8  bit  enum) 

char_strings[ll]  (8  bit  unsigned  int)  =  00000000000 

}; 

capabilities  =  0x0  (32  bin  boolean) 
num_articulate_params  =  2  (8  bit  unsigned  int) 
articulat_params_head  =  { 

[0]  =  { 

change  =  10  (16  bit  unsigned  int) 
id_attached_to  =11  (16  bit  unsigned  int) 
parameter_type  =12  (32  bit  enum) 

parameter_value[8]  (8  bit  unsigned  int)  =  31000000  128 

}; 

[i]  =  { 

change  =  20  (16  bit  unsigned  int) 
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id_attached_to  =  21  (16  bit  unsigned  int) 
paranieter_type  =  22  (32  bit  enum) 

parameter_value[8]  (8  bit  unsigned  int)  =  32  1  0  28  16  1  43  32 


>; 

>; 

} 

ASCII-Binary  Log  Format 

Below  is  the  same  EntityStatePDU  logged  in  the  ASCII-binaiy  format  with  a  header.  The 
version  of  the  DIS  protocol  being  used  is  2.0.3.  This  format  prints  each  bit  of  the  PDU  as  an 
ASCII  one,  “1,”  or  zero,  “0.” 

176  Thu  Oct  20  08:07:59.037769  INCOMING 

00000011000000010000000100000000000000000000000000000000000000000000000010110000000000000000 
00000000000000100101000000000011010100000000000000010000001000000010000000000000000000000000 
00000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000 
00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 
000000000000000000 11111111 110000000000000000000000000000000000000000000000000000010000000000 
00000000000000000000000000000000000000000000000000000100000000001000000000000000000000000000 
00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 
00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 
oooooooooooooooooooooooooooooooooooooooooobooooooooooooooooooooooooooooooooooooooooooooooooo 
00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 
00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 
oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo 
00000000000000000000000000000000000000000000000000000000000010100000000000001011000000000000 
00000000000000001100000111110000000000000000000000000000000000000000000000001000000000000000 
00010100000000000001010100000000000000000000000000010110001000000000000100000000000111000001 
0000000000010010101100100000 
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DIS_MGR(1) 


DIS_MGR(1) 

NAME 

.dis_mgr  -  facility  for  sending  and  receiving  Distributed  Interactive  Simulation  (DIS)  pro¬ 
tocol  data  units  (PDU) 

SYNOPSIS 

disjngr  [-v]  [-n  networkjnterface]  [-c  num_clients]  [-r  recv  -s  send]  [-1  filename  [-a  |  -b  | 

I  -ab]  [-i  I  -in  |  -incoming]  [-o  |  -out  |  -outgoing]  [  -h  |  -hn]  [-ap  |  -append]  [-over  |  -over¬ 
write] 

DESCRIPTION 

dis_mgr  is  a  program  that  provides  network  communication  services  to  application  pro¬ 
grams  that  wish  to  send  and  receive  DIS  PDUs  across  a  network.  It  uses  TCP/UDP  for  ex¬ 
changing  PDUs  on  the  network.  It  acts  as  a  server  to  client  application  programs  maintain¬ 
ing  a  TCP/IP  based  connection  over  which  incoming  and  outgoing  PDUs  are  passed 
between  the  dis  mgr  and  client  programs. 

The  purpose  of  the  dis^mgr  is  to  provide  a  common  service  to  DIS  application  programs 
That  service  is  to  establish  and  maintain  network  connections  through  which  DIS  PDUs 
can  be  sent  to  and  received  from  other  DIS  apphcations.  The  dis_mgr  alleviates  applica¬ 
tion  programs  from  the  burden  of  having  to  establish  and  maintain  such  a  network  connec¬ 
tion  themselves.  Application  programs  wishing  to  use  this  facility  must  include  the  dis_mgr 
library,  jibdis.  This  library  contains  the  function  calls  through  which  the  services  of  the 
dis  mgr  are  accessed. 

OPTIONS 

Verbose  mode.  This  option  causes  the  dis  mgr  to  detail  its  actions 
through  standard  output. 

n6t_iface  specifies  the  name  of  the  ethemet  connection  over 
which  PDUs  will  be  broadcast  and  received,  e.g.,  leO. 

num  clients  indicates  the  maximum  number  of  client  application 
programs  that  can  use  the  services  of  the  dis  mgr  at  any  one  time. 
Default  is  4. 

rocv  and  send  are  used  to  specify  alternate  UDP  port  numbers 
that  the  dis  mgr  will  use  to  send  and  receive  DIS  PDUs  over  the 
network.  This  is  useful  if  more  than  one  independent  DIS  exer¬ 
cise  is  being  conducted  simultaneously  on  the  same  network. 

Turns  on  the  logger  facility  within  the  dis  mgr.  Logged  PDUs  are 
written  to  the  file  called  filename. 

Format  of  logfile.  -  PDUs  are  logged  in  straight  ASCII,  i  - 
PDUs  are  logged  in  binary,  ^ab  -  PDUs  are  logged  in  ASCII- 
binaiy,  that  is,  the  binary  representation  of  each  PDU  is  logged 
in  the  file  as  a  series  of  ASCII  one’s  (“1”)  and  zeros  (“0”).  This 
mode  is  to  facilitate  debugging  when  it  is  necessary  to  see  the  ac¬ 
tual  bit  stream  of  a  PDU.  Binary  is  default  format  when  -1  option 
is  specified. 


-V 

-n  netiface 
-c  numclients 

-r  recv  -s  send 

-1  filename 
-a  I  -b  I  -ab 
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DIS_MGR(1) 

-i  I  -in  I  -incoming 

-o  I  -out  I  -outgoing 

-h  I  -hn 

-ap  I  -append 
-over  I  -overwrite 

SEE  ALSO 
libdis(l). 


DIS_MGR(1) 

For  logging  PDUs,  this  option  indicates  that  only  incoming  PDUs 
are  to  be  logged.  On  by  default  when  -1  option  is  specified. 

For  logging  PDUs,  this  option  indicates  that  only  outgoing  PDUs 
are  to  be  logged.  On  by  default  when  -1  option  is  specified. 

PDUs  can  be  logged  with  a  header  detailing  the  time,  length,  and 
direction  (incoming  or  outgoing)  of  the  PDU.  -h  (the  default) 
turns  logging  with  headers  on  and  -hn  turns  it  off. 

Indicates  that  logged  PDUs  should  be  appended  to  the  logfile. 

Indicates  that  logged  PDUs  should  overwrite  anything  previously 
existing  in  the  logfile. 
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libdis(l) 

NAME 


libdis(l) 


libdis  -  software  library  of  C  routines  for  interfacing  to  the  Distributed  Interactive  Simula¬ 
tion  (DIS)  Network  Manager  program,  dis_mgr. 

SYNOPSIS 

#include  <dis_lib.h>  -  located  in  src/H  under  the  source  directory  of  the  DIS  Network 

Manager  distribution. 

int  dis_open(  char  *  host ) 

int  dis_close(  void  ) 

int  dis_register_pdu(  char  *  pdu_list ) 

int  dis_ignorejpdu(  char  *  pdu_list ) 

int  dis_send(  char  *  pdu ) 

int  dis_read(  char  **  pdu) 

pdujype  *  %eiJPduType¥D\}{ ) 

void  fTe^_PduTypeYD\i{  pdujype  *  pdu  ) 

char  *  ptmtJPduiype{pduJype  *  pdu) 

int  NEW_ENnTY_ID(  void  ) 

int  my_pdu(  char  *  pdu ) 

DESCRIPTION 

These  routines  constitute  the  DIS  Network  Manager  library  libdis.  libdis  is  a  collection  of 
C  routines  that  implement  a  TCP/IP  based  communication  interface  between  an  applica¬ 
tion  program  and  the  dis  mgr  program.  The  purpose  is  to  facilitate  the  exchange  of  DIS 
protocol  data  units  (PDU)  with  other  DIS  application  programs  on  the  network.  (See 
dis_mgr(l).) 

dis_open  establishes  a  TCP/IP  based  network  connection  between  an  application  pro¬ 
gram,  hereafter  referred  to  as  client,  and  a  dis  mgr.  host  is  an  ASCII  character  string  for 
the  standard  network  node  hostname  of  the  computer  on  which  dis  mgr  is  running.  This 
routine  must  be  used  by  a  client  before  any  other  libdis  routines.  If  successful,  it  returns 
a  value  of  TRUE  (1),  otherwise  FALSE  (0)  is  returned.  dis_close  closes  or  terminates  a 
connection  between  a  client  and  the  dis  mgr. 

dis_register_pdu  is  used  by  clients  to  tell  the  dis  mgr  which  type  of  PDUs  it  wishes  to  have 
sent  to  it.  Conversely,  dis_ignore  jpdu  is  used  to  specify  which  types  of  PDUs  are  not  to  be 
sent  to  the  client.  For  both  of  these  routines  pdu  list  is  a  white  space  separated  list  of  PDU 
types  (by  number).  For  example,  “125.”  The  PDU  types  by  number  are  listed  in  the  DIS 
header  file  “dis_lib.h.”  Clients  can  use  these  two  routines  to  control  which  types  of  incom¬ 
ing  PDUs  the  dis_mgr  will  send  to  it.  This  enables  clients  to  only  have  to  handle  PDUs  that 
it  wants  to  process.  dis_registerjpdu  and  dis_ignore_pdu  return  TRUE  (1)  if  successful 
and  DL_B  AD_NETCONN  ( -  2)  if  a  dis_mgr  connection  has  not  been  established  or  does 
not  exist  for  some  reason. 


25 


libdis(l)  libdis(l) 

dis_send  is  a  routine  that  clients  use  to  pass  a  PDU  to  the  dis  mgr  for  transmission  across 
thelietwork  to  all  other  listening  DIS  applications.  The  argument,  pdu,  is  a  pointer  to  a  C 
data  structure  that  describes  the  PDU.  This  pointer  must  be  typecast  as  a  (char  *)  before 
being  used  in  dis_send.  The  “dis_lib.h”  header  file  contains  C  data  structures  for  every  type 
of  PDU  that  fully  correspond  to  the  PDU  definitions  as  described  in  the  proposed  IEEE 
Standard  Draft:  Standard  for  Information  Technology  -  Protocob  for  Distributed  Interactive 
Simulation  Applications,  Version  2.0  Drafts  2  and  3,  Institute  for  Simulation  and  Training, 
Orlando,  FL.  dis_send  returns  DL_BAD_NETCONN  (-2)  if  there  is  not  a  good  network 
connection  to  th^dis  mgr.  DL_BAD_PDU  (- 1)  is  returned  if  an  unrecognized  PDU  type 
is  sent  or  if  the  PDU  structure  could  not  be  converted  into  a  binary  stream  for  some  reason. 
If  successful,  dis_send  returns  TRUE  (1). 

dis_read  is  a  routine  used  by  clients  to  receive  the  next  incoming  PDU  that  has  been  for¬ 
warded  to  it  by  the  dis  mgr.  The  argument,  pdu.  is  to  be  the  address  of  a  pointer  so  that 
dis_read  can  set  it  to  point  to  the  place  in  memory  where  the  next  incoming  PDU  resides. 
dis_read  returns  an  integer  that  corresponds  to  the  incoming  PDU  type  by  number  (as 
listed  in  “disjib.h”),  DL_NO_DATA  (0)  indicating  that  there  is  no  PDU,  or 
DL_BAD_NETCONN  (-2)  if  the  network  connection  does  not  exist  or  is  bad.  dis_read 
operates  on  the  principle  that  clients  will  request  the  next  incoming  PDU  from  the  dis^mgr, 
hence  dis_read  should  be  used  in  the  main  loop  of  the  client  program  and  called  as  fre¬ 
quently  as  possible. 

A  set  of  routines  of  the  form  get_PduTypeFDV  exist  that  return  a  pointer  to  a  dynamically 
allocated  PDU  data  structure  suitable  for  use  by  the  client  program.  In  this  structure,  the 
site  and  host  fields  are  initialized  to  their  correct  values  by  the  get_PduTypeFTyV  routine. 
In  actual  u.se,pdu_type  should  be  replaced  with  the  name  of  a  valid  PDU  t5q)e.  For  example, 
to  dynamically  allocate  an  Entity  State  PDU  structure,  use  get_EntityStatePDU.  A  corre¬ 
sponding  set  of  routines  of  the  form  freeJPduTypePDV  exist  for  freeing  dynamically  allo¬ 
cated  memory  obtained  via  the  getJPduTfpePDV  routines. 

Similarly,  a  set  of  routines  of  the  form  printJPduType  exist  for  printing  the  contents  of  a 
PDU.  pdu  is  a  pointer  to  the  C  data  structure  formatted  PDU  that  is  to  be  printed.  These 
routines  return  a  pointer  to  a  new  string  containing  the  contents  of  pdu  suitable  for  use  with 
any  of  the  C  string(3C)  functions.  The  returned  string  must  be  used  or  copied  before  a 
successive  call  to  the  same  print_PduType  routine. 

NEW_EN'nTY_ID  is  a  routine  that  returns  the  next  available  entity  number  for  use  in  the 
Entity  Identification  field  of  PDUs.  It  is  to  be  used  every  time  a  new  entity  is  created  by 
a  client.  This  function  ensures  unique  entity  ID  numbers  among  all  clients  of  a  particular 
dis  mgr,  myjpdu  takes  a  pointer  to  a  PDU  data  structure,  pdu,  cast  as  a  (char  *)  and  deter¬ 
mines  if  it  is  a  PDU  that  originated  from  the  client  using  this  routine.  If  so,  it  returns  TRUE 
(1),  otherwise  FALSE  (0)  is  returned. 

SEE  ALSO 

dis_mgr(l). 
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LIST  OF  ACRONYMS 


ACISD 

ARL 

DIS 

GUI 

ID 

LAN 

PDU 

SMB 

TCP/IP 

TCP/UDP 


Advanced  Computational  and  Informational  Sciences  Directorate 

U.S.  Army  Research  Laboratory 

Distributed  Interactive  Simulation 

Graphical  User  Interface 

Identification 

Local  Area  Network 

Protocol  Data  Unit 

Simulation  Methodology  Branch 

Transport  Control  Protocol/Intemet  Protocol 

Transport  Control  Protocol/User  Datagram  Protocol 
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